/**
 *  This file is part of TaoBaoItemImporter.
 *
 *   TaoBaoItemImporter is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   TaoBaoItemImporter is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with TaoBaoItemImporter.  If not, see <http://www.gnu.org/licenses/>. 
 */
package com.googlecode.ulysses.taobao;

import com.googlecode.ulysses.taobao.data.Item;
import com.mongodb.DBCollection;

/**
 * A base interface for all Importer classes.
 * 
 * @author Ulysses <robman1070@gmail.com>
 * 
 */
public interface ItemMongoWriter {

	/**
	 * Insert an item object as a document into a Mongo collection.
	 * 
	 * Upon a successful insertion, one will see a new document in the
	 * corresponding MongoDB. This method can be regarded as the combination of
	 * the adding methods and writing method.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @see ItemMongoWriter#addItemMainToCollection(DBCollection coll, Item item)
	 * @see ItemMongoWriter#addItemPropertyToCollection(DBCollection coll, Item item)
	 * @see ItemMongoWriter#addItemBuyLinkToCollection(DBCollection coll, Item item)
	 * @see ItemMongoWriter#write(DBCollection coll)
	 */
	public void importItemToCollection(DBCollection coll, Item item);

	/**
	 * Add the property part of the given item to the collection object.
	 * 
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * 
	 */
	public DBCollection addItemMainToCollection(DBCollection coll, Item item);

	/**
	 * Add the property part of the given item to the collection object.
	 * 
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * 
	 */
	public DBCollection addItemPropertyToCollection(DBCollection coll, Item item);

	/**
	 * Add the buyLink part of the given item to the collection object.
	 * 
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * 
	 */
	public DBCollection addItemBuyLinkToCollection(DBCollection coll, Item item);
	
	/**
	 * Add and/or update fields of a document in the given collection.
	 * 
	 * This method combines adding and updating operations.
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * @see ItemMongoWriter#updateItemFieldToCollection(DBCollection coll, Item item)
	 * 
	 */
	public DBCollection addAndUpdateItemFieldToCollection(DBCollection coll, Item item);
	
	/**
	 * Add fields of a document in the given collection.
	 * 
	 * This will overwrite the value of the existing field with the same key.
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * @see ItemMongoWriter#addItemFieldToCollection(DBCollection coll, Item item)
	 * 
	 */
	public DBCollection addItemFieldToCollection(DBCollection coll, Item item);
	
	/**
	 * Update fields of a document in the given collection.
	 * 
	 * This will overwrite the value of the existing field with the same key.
	 * This operation takes place locally, meaning no data should be written
	 * into MongoDB. To do so use the method <em>write</em>.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 * @param item
	 *            An item object to import
	 * @return A modified collection object
	 * @see ItemMongoWriter#write(DBCollection coll)
	 * @see ItemMongoWriter#addAndUpdateItemFieldToCollection(DBCollection coll, Item item)
	 * 
	 */
	public DBCollection updateItemFieldToCollection(DBCollection coll, Item item);

	/**
	 * Write the collection objection into the database.
	 * 
	 * @param coll
	 *            A Mongodb collection object
	 */
	public void write(DBCollection coll);

}
